Adds topic required form fields to the Web forms section #210

rianrietveld · 2025-10-27T11:45:14Z

Related issue: #160
Preview: https://wpaccessibility.org/pr-preview/pr-210/docs/topics/forms/required/.

The page required is now a section with 4 pages:

Intro page Indicate required fields in forms
Mark required fields
Mark non-required fields
Mark required for screen readers

github-actions · 2025-10-27T11:46:32Z

PR Preview
🚀 View PR Preview at https://wpaccessibility.org/pr-preview/pr-210.
If you see a 404 error, please wait a few minutes and refresh the page.
2025-10-28 10:28 UTC

assets/images/mark-required-form-fields.png

docs/topics/forms/required/index.md

docs/topics/forms/required/mark-non-required-fields.md

docs/topics/forms/required/mark-required-fields.md

docs/topics/forms/required/required-screen-readers.md

jaapwiering · 2025-10-27T13:15:38Z

"Both are fine, as long as you are consistent within the form and if possible also withing all forms on your website." Change "withing" to "within".

@GaryJones

props @GaryJones @michaelhastrich @jaapwiering

rianrietveld · 2025-10-28T07:11:03Z

@GaryJones, @michaelhastrich, @jaapwiering
Thanks for the feedback, I made the suggested changes.

rianrietveld · 2025-10-28T07:13:24Z

@joedolson can you have a read too?

joedolson

Some misc. changes.

joedolson · 2025-10-28T14:35:31Z

docs/topics/forms/required/index.md

+
+# Indicate required fields in forms
+
+Clearly indicate to the user whether a form field is required to fill out or not.


Simplify: "Clearly indicate to the user whether a form field is required."

The rest of the sentence is unneeded.

joedolson · 2025-10-28T14:37:08Z

docs/topics/forms/required/index.md

+# Indicate required fields in forms
+
+Clearly indicate to the user whether a form field is required to fill out or not.
+Then the user knows which information they must provide to submit a form. 


"Then the user can tell what information they must provide..."

In principle, while making this accessible should make it more probable that a user will know what they need, it technically only makes it possible for them to know it. So I don't like saying "they will know this", just that "they can know this".

joedolson · 2025-10-28T14:38:56Z

docs/topics/forms/required/index.md

+
+Both are fine, as long as you are consistent within the form and, if possible, also within all forms on your website.
+
+Always place the explanation of how you indicate this above the form, so the user knows beforehand what to expect when completing it. 


Maybe: "Always explain how you are indicating required fields above the form..."

joedolson · 2025-10-28T14:40:07Z

docs/topics/forms/required/index.md

+Clearly indicate to the user whether a form field is required to fill out or not.
+Then the user knows which information they must provide to submit a form. 
+
+You have two options:


This seems awkward as a list. As a sentence, I might go with:

"You can either add a visual indicator for all required fields, or add a visual indicator for all optional fields."

I'm just not convinced that a list of two items is helping the reader.

joedolson · 2025-10-28T14:41:53Z

docs/topics/forms/required/mark-non-required-fields.md

+nav_order: 3
+---
+
+# Option 2: Marking only the non-required form fields


Omit "the": "Marking only non-required form fields"

Question: do we want to say "non-required" or "optional"? I feel that optional is clearer and easier to read. Having the variants be "required" and "non-required" means that you have to read more carefully to be sure whether you're looking at the right instructions. This is something consistent through these docs.

joedolson · 2025-10-28T14:50:29Z

docs/topics/forms/required/mark-required-fields.md

+
+
+{: .alert }
+**Note for developers**: for screen reader users the indication if a field is required must be added in the code with a form field. Read [Mark if a form field is required for screen readers]({{site.baseurl}}/docs/topics/forms/required/required-screen-readers/) about how to do this.


The construction "if a field is required must be added in the code with a form field" is confusing; I think that could be clarified. It could also be omitted: I think it would be sufficient here to say "Screen readers have specific needs for discovering required fields. Learn how to indicate required fields for screen readers."

joedolson · 2025-10-28T14:52:50Z

docs/topics/forms/required/required-screen-readers.md

+
+# Mark a required form field for screen readers
+
+Screen reader users will have the field announced as required by the HTML attributes `aria-required` or `required` on the form field.


Simplify: "Screen readers announce form fields as required if they have the HTML attributes aria-required or required."

joedolson · 2025-10-28T14:56:26Z

docs/topics/forms/required/required-screen-readers.md

+
+The disadvantage of using `required` is, that it triggers the [client-side form validation](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) of the browser. 
+
+At the time of writing, this validation does not meet WCAG accessibility guidelines. The error messages are not specific enough, they disappear after a few seconds, and they currently lack sufficient screen reader support.


Very technically, browser validation does meet WCAG guidelines, but only because of the exceptions about the appearance and behavior of the interaction being governed by the user agent and not modified by the author. So I'd argue that this should say "is not accessible", rather than "does not meet WCAG".

In the Netherlands this is a hard WCAG fail for several SC, I, will add more info and resources why this is not reliable enough at the moment.

joedolson · 2025-10-28T14:57:24Z

docs/topics/forms/required/required-screen-readers.md

+
+At the time of writing, this validation does not meet WCAG accessibility guidelines. The error messages are not specific enough, they disappear after a few seconds, and they currently lack sufficient screen reader support.
+
+If you decide to use `required`, also use `novalidate` on the form element to prevent the browser's form validation from kicking in and enable you to handle validation server-side.


Add: "You can write your own custom client-side validation, as long as you ensure that it's accessible!"

I don't agree, will add more info and resources why this is not reliable enough at the moment.

adds topic required form fields

f2cb05b

rianrietveld self-assigned this Oct 27, 2025

rianrietveld added this to WP A11y docs Oct 27, 2025

rianrietveld moved this to PRs to review in WP A11y docs Oct 27, 2025

rianrietveld linked an issue Oct 27, 2025 that may be closed by this pull request

[Topic] Indicate required fields in forms #160

Open

rianrietveld requested review from GaryJones and joedolson October 27, 2025 11:51

GaryJones reviewed Oct 27, 2025

View reviewed changes

Apply suggestions from text review

a4d8b83

props @GaryJones @michaelhastrich @jaapwiering

rianrietveld added 2 commits October 28, 2025 11:25

change example to an easier one

1c128d5

fix uneven spaces

2a7bf3e

joedolson requested changes Oct 28, 2025

View reviewed changes


		# Indicate required fields in forms

		Clearly indicate to the user whether a form field is required to fill out or not.


		Both are fine, as long as you are consistent within the form and, if possible, also within all forms on your website.

		Always place the explanation of how you indicate this above the form, so the user knows beforehand what to expect when completing it.



		{: .alert }
		Note for developers: for screen reader users the indication if a field is required must be added in the code with a form field. Read [Mark if a form field is required for screen readers]({{site.baseurl}}/docs/topics/forms/required/required-screen-readers/) about how to do this.


		# Mark a required form field for screen readers

		Screen reader users will have the field announced as required by the HTML attributes `aria-required` or `required` on the form field.


		The disadvantage of using `required` is, that it triggers the [client-side form validation](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) of the browser.

		At the time of writing, this validation does not meet WCAG accessibility guidelines. The error messages are not specific enough, they disappear after a few seconds, and they currently lack sufficient screen reader support.


		At the time of writing, this validation does not meet WCAG accessibility guidelines. The error messages are not specific enough, they disappear after a few seconds, and they currently lack sufficient screen reader support.

		If you decide to use `required`, also use `novalidate` on the form element to prevent the browser's form validation from kicking in and enable you to handle validation server-side.

Adds topic required form fields to the Web forms section #210

Are you sure you want to change the base?

Adds topic required form fields to the Web forms section #210

Uh oh!

Conversation

rianrietveld commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jaapwiering commented Oct 27, 2025

Uh oh!

rianrietveld commented Oct 28, 2025

Uh oh!

rianrietveld commented Oct 28, 2025

Uh oh!

joedolson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

rianrietveld commented Oct 27, 2025 •

edited

Loading

github-actions bot commented Oct 27, 2025 •

edited

Loading